Executing the Windows Command Processor

If Y is a simple character vector, ⎕CMD invokes the Windows Command Processor (normally cmd.exe) and passes the command specified by character vector Y to it for execution. The term command means here an instruction recognised by the Command Processor, or the pathname of a program (with optional parameters) to be executed by it. In either case, APL waits for the command to finish and then returns the result R, a vector of character vectors containing its result. Each element in R corresponds to a line of output produced by the command.

Example

      Z←⎕CMD'dir'
      ⍴Z
12
      ↑Z
 Volume in drive C is OS
 Volume Serial Number is B438-9B76

 Directory of C:\Users\Pete\Documents\Dyalog APL-64 17.0 Unicode Files

23/06/2018  15:59    <DIR>          .
23/06/2018  15:59    <DIR>          ..
23/06/2018  14:53           181,488 default.dlf
13/06/2018  20:13         1,262,296 def_uk.dse
14/06/2018  14:36           108,976 UserCommand20.cache
               3 File(s)      1,552,760 bytes
               2 Dir(s)  101,371,097,088 bytes free

If the command specified in Y already contains the redirection symbol (>) the capture of output through a pipe is avoided and the result R is empty.  If the command specified by Y issues prompts and expects user input, it is ESSENTIAL to explicitly redirect input and output to the console.

If this is done, APL detects the presence of a ">" in the command line, runs the command processor in a visible window, and does not direct output to the pipe.  If you fail to do this your system will appear to hang because there is no mechanism for you to receive or respond to the prompt.

      ⎕CMD 'DATE <CON >CON'

   C:\Program Files\Microsoft Office\OFFICE11\excel.exe

⎕CMD '"c:\program files\microsoft office\office11\excel.exe"'

Double-Quote Restriction

The Windows Command Processor does not permit more than one set of double-quotes in a command string.

The following statements are all valid:

⎕CMD 'c:\windows\system32\notepad.exe c:\myfile.txt'  
⎕CMD 'c:\windows\system32\notepad.exe "c:\myfile.txt"'
⎕CMD '"c:\windows\system32\notepad.exe" c:\myfile.txt'

Whereas the next statement, which contains two sets of double-quotes, will fail:

⎕CMD '"c:\windows\system32\notepad.exe" "c:\myfile.txt"'

Such a statement can however be executed using the second form of ⎕CMD(where the argument is a 2-element vector of character vectors) which does not use the Windows Command Processor and is not subject to this restriction. However, the call to ⎕CMD will return immediately, and no output from the command will be returned.

⎕CMD'"c:\windows\system32\notepad.exe" "c:\myfile.txt"' ''

Implementation Notes

The right argument of ⎕CMD is simply passed to the appropriate command processor for execution and its output is received using an unnamed pipe. 

By default, ⎕CMD will execute the string ('cmd.exe /c',Y); where Y is the argument given to ⎕CMD.  However, the implementation permits the use of alternative command processors as follows:

Before execution, the argument is prefixed and postfixed with strings defined by the APL parameters CMD_PREFIX and CMD_POSTFIX.  The former specifies the name of your command processor and any parameters that it requires.  The latter specifies a string which may be required.  If CMD_PREFIX is not defined, it defaults to the name defined by the environment variable COMSPEC followed by  "/c".  If COMSPEC is not defined, it defaults to cmd.exe.  If CMD_POSTFIX is not defined, it defaults to an empty vector.

If you simply wish to open a Command Prompt window, you may execute the command as a Windows Program (see below).  For example:

      ⎕CMD 'cmd.exe' ''

Starting a Windows Program

If Y is a 2-element vector of character vectors, ⎕CMD starts the executable program named by Y[1] with the initial window parameter specified by Y[2].  The shy result is an integer scalar containing the window handle allocated by the window manager. Note that in this case APL does not wait for the program specified by Y to finish, but returns immediately. The shy result R is the process identifier (PID).

Note that Y[1] may contain the complete command line, including any suitable parameters for starting the program.  If Windows fails to find the executable program, ⎕CMD will fail and report FILE ERROR 2.

There is no way to terminate an application started by ⎕CMD from APL; it will run until it completes or is terminated by an external mechanism. Furthermore, if the window parameter is HIDDEN, the user is unaware of the application (unless it makes itself visible) and has no means to close it.

Examples

      Path←'c:\Program Files\Microsoft Office\Office\'
      ⎕←⎕CMD (Path,'excel.exe') ''
33
      ⎕CMD (Path,'winword /mMyMacro') 'Minimized'

Executing Programs

Either form of ⎕CMD may be used to execute a program. The difference is that when the program is executed via the Command Processor, APL waits for it to complete and returns any result that the program would have displayed in the Command Window had it been executed from a Command Window. In the second case, APL starts the program (in parallel).

Note:

This function is disabled and instead generates a DOMAIN ERROR if the RIDE_SPAWNED parameter is non-zero. This is designed to prevent it being invoked from a RIDE session which does not support this type of user interface. For further details, see the RIDE User Guide.